OpenEdge Development:<br />Open Client Introduction and Programming The object model

To define an Open Client interface, ProxyGen requires that you organize an application service into three types of proxy objects:

Application objects (AppObjects)

Sub-application objects (SubAppObjects)

Procedure objects (ProcObjects)

Note: OpenEdge supports an API (OpenAPI) for Java and .NET Open Clients that allows you to directly access an AppServer application service from an Open Client without the need to define and generate proxy objects using ProxyGen. However to use this API, you must organize and manage all access to the AppServer at run time. Although, you do not use proxy objects with the OpenAPI, the basic principles of working with AppObjects and ProcObjects also apply to accessing an AppServer using the OpenAPI. For more information on the OpenAPI, see Chapter 4, " Programming Concepts."

All these proxy objects organize 4GL procedures on the AppServer, but in different ways. The following sections describe the different ways of organizing proxy objects and contain information about:

4GL procedures

Before describing the three types of proxy objects, it helps to understand basic concepts governing the operation of 4GL procedures. First, any file that is executable by Progress is an external procedure. An external procedure can contain one or more internal procedures or user-defined functions that execute within and share the context of the external procedure. You can execute an external procedure in two ways:

As a non-persistent procedure — The procedure executes and returns to the caller, removing all trace of its context from memory after returning. Any internal procedures and functions that it defines can be executed only by the procedure itself. A non-persistent procedure executes and returns as a unit without exposing any of its context to the caller.

As a persistent procedure — The procedure leaves its context active after completing execution of the main block. Internal procedures and user-defined functions remain available for future execution. A persistent procedure instantiates a procedure object that exposes its context to the caller through the internal procedures and user-defined functions it defines. For more information on 4GL procedures, see OpenEdge Development: Progress 4GL Handbook .

AppObjects

Each AppObject encapsulates a set of business logic deployed at a particular AppServer and establishes a connection to that AppServer (session-managed) or to the application service represented by one or more AppServers accessed from a connection pool (session-free).

Although you can encapsulate an AppServer’s entire functionality (application service) within one AppObject, dividing a large AppServer application into one AppObject and several SubAppObjects offers advantages, particularly for session-managed applications. Multiple objects provide better logical organization and separate name spaces for each object. Also, they help avoid the instantiation of large objects that may be slow to load and difficult to maintain.

For session-free applications, it is often best to define the entire application service within the AppObject alone. The behavior of session-free connections makes other types of Open Client objects less useful, and even an obstacle to good session-free application performance, as the following sections describe.

SubAppObjects

Each SubAppObject encapsulates a set of business logic deployed at a particular AppServer. It differs from an AppObject only in that it does not establish its own connection to an AppServer but shares the one established by its associated AppObject.

The associated AppObject defines a class factory method for creating each SubAppObject that shares its AppServer connection. This method exchanges no communications with the AppServer; rather, it only performs operations to instantiate the SubAppObject on the client.

SubAppObjects are less useful for session-free applications, especially for those that support Web services. For .NET and Java Open Clients, SubAppObjects can help to organize functionality for session-free application services. However, because of the implementation of SubAppObjects for Web services, SubAppObjects add complexity to Web service request management on the client that you might want to avoid. Therefore, if you intend your Open Client interface to define Web services, you might prefer to avoid the use of SubAppObjects and encapsulate the application service interface in the single AppObject for all Open Clients that use it. For more information on how SubAppObjects work with session-free Web services, see OpenEdge Development: Web Services .

ProcObjects

Each ProcObject encapsulates one persistent procedure running on an AppServer. The ProcObject exposes all non-PRIVATE internal procedures and user-defined functions to the client that you do not explicitly omit in ProxyGen when you define the ProcObject.

A ProcObject shares a connection established by an associated AppObject. You can create the ProcObject using a class factory method on the AppObject or SubAppObject to which this procedure was added in ProxyGen.

When you call the ProcObject class factory method on the AppObject or SubAppObject, it creates the ProcObject on the client and executes the corresponding procedure persistently on the AppServer. Any parameters required by this procedure are required as parameters on the class factory method. The ProcObject saves a handle to the persistent procedure for future calls to its internal procedures and functions and for releasing and disconnecting the object from the AppServer application.

For session-free applications, ProcObjects have limited utility and tend to interfere with session-free application performance. Part of the value from ProcObjects is that they provide a means to maintain run-time context between the client and AppServer. Much of the value from session-free application services is that AppServer resources are more readily available to serve client requests. However, a ProcObject reserves an AppServer resource for use by the client that instantiates the ProcObject until that ProcObject is released. This ties up a physical connection and reduces the AppServer resources available for requests from other clients, which can in turn reduce apparent application performance across the client domain, possibly to intolerable levels if every client instantiates a ProcObject and AppServer resources are scarce to begin with.

Therefore, Progress Software Corp. strongly recommends that you avoid the use of ProcObjects in session-free applications.

Progress ADM SmartObjects and SmartDataObjects (Java only)

The AppBuilder, which is part of the OpenEdge Application Development Environment (ADE), allows you to build preprogrammed persistent procedures that adhere to the OpenEdge Application Development Model (ADM). The ADM allows you to build persistent procedures as reusable application building blocks known as SmartObjects. The Open Client Toolkit allows you to access a type of SmartObject known as a SmartDataObject, which dynamically accesses and updates temp-table data. As a result, you can run a SmartDataObject on the AppServer like any persistent procedure and, using the Open Client Runtime, you can access the SmartDataObject from a Java application. For more information on SmartDataObjects, see OpenEdge Development: AppBuilder .

In Java, you also can access the SmartDataObject as an extended Java Database Connectivity (JDBC) 2 ResultSet.

Object relationships

In an Open Client application, you create an AppObject first, to establish a connection to an AppServer (session-managed) or application service (session-free). Then you can create SubAppObjects (through the associated AppObject) and ProcObjects (through an associated AppObject or SubAppObject). You use a special Class Factory method to create a SubAppObject or ProcObject. A proxy or Web Service definition comprises one AppObject and all SubAppObjects and ProcObjects that share the same AppServer connection.

Although there is a creation hierarchy among the different types of proxy objects, there is no functional hierarchy. All objects share the AppServer connection with equal status. Objects can be released (have their context removed from client memory) in any order, with no effect on objects still in use. The AppServer (session-managed) or application service (session-free) connection remains intact until the last object using it is released.

Table 1–1 summarizes how each type of proxy object encapsulates and accesses AppServer functionality.

Table 1–1: Types of proxy objects
This type of proxy object ...	Provides this functionality ...
AppObject	A connection to an AppServer (session-managed) or application service (session-free). Application methods that execute Progress non-persistent procedure files. Class factory methods that create SubAppObjects. Class factory methods that create ProcObjects. (Java Only) A special class factory method that creates a built-in ProcObject for accessing a remote Progress SmartDataObject as an extended JDBC 2 ResultSet.
SubAppObject	A shared AppServer (session-managed) or application service (session-free) connection through an AppObject. Application methods that execute Progress non-persistent procedure files. Class factory methods that create ProcObjects. (Java Only) A special class factory method that creates a built-in ProcObject for accessing a remote Progress SmartDataObject as an extended JDBC 2 ResultSet.
ProcObject	A shared AppServer (session-managed) or application service (session-free) connection through an AppObject. Execution of a remote Progress persistent procedure. Application methods that execute Progress internal procedures and user-defined functions.

In addition to the functionality described in Table 1–1, each object type from the Open Client object model provides a set of common methods for run-time management of the object and its application service connection.

Open Client access to objects

Once you define an AppObject, its application methods and any related SubAppObjects and ProcObjects, ProxyGen can generate the proxy or Web service definition that exposes these objects to Open Clients.

For Java and .NET clients, the client code accesses the proxy in the client’s native environment. As a result, a Java client sees the proxy (and the AppServer application service) as a set of Java classes, while a .NET client sees the proxy as a set of .NET classes. To use proxy objects, you must deploy the generated proxy along with the Open Client Runtime to all client application development and deployment systems. See Chapter 2, " Configuration."

For Web service clients, the client accesses the Web service in the client’s native environment. The Web service definition (the WSDL document) is available through the WSA instance hosting the Web service. To use the Web service, there is no deployment requirement for the client.